package com.alibaba.otter.canal.instance.core;

import com.alibaba.otter.canal.common.CanalLifeCycle;
import com.alibaba.otter.canal.common.alarm.CanalAlarmHandler;
import com.alibaba.otter.canal.meta.CanalMetaManager;
import com.alibaba.otter.canal.parse.CanalEventParser;
import com.alibaba.otter.canal.protocol.ClientIdentity;
import com.alibaba.otter.canal.sink.CanalEventSink;
import com.alibaba.otter.canal.store.CanalEventStore;

/**
 * 代表单个canal实例，比如一个destination会独立一个实例
 *
 * canal的instance模块中有三个子模块：core, spring, manager
 * 在core模块中，定义了CanalInstance接口，以及其抽象类子类AbstractCanalInstance。
 * 在spring模块，提供了基于spring配置方式的CanalInstanceWithSpring实现，
 *   即CanalInstance实例的创建，通过spring配置文件来创建。
 * 在manager模块中，提供了基于manager配置方式的CanalInstanceWithManager实现，
 * 即CanalInstance实例根据远程配置中心的内容来创建。
 *
 * canal instance有四大组件：
 * event parser：数据源接入，模拟slave协议和master进行交互，协议解析
 * event sink：parser和store链接器，进行数据过滤，加工，分发的工作
 * event store：数据存储
 * meta manager：增量订阅/消费binlog元数据位置存储
 *
 * CanalEventParser接口实现类：
 *   MysqlEventParser：伪装成单个mysql实例的slave解析binlog日志
 *   GroupEventParser：伪装成多个mysql实例的slave解析binlog日志。内部维护了多个CanalEventParser。
 *   主要应用场景是分库分表：比如产品数据拆分了4个库，位于不同的mysql实例上。
 *   正常情况下，需要配置四个CanalInstance。对应的，业务上要消费数据时，需要启动4个客户端，分别链接4个instance实例。
 *   为了方便业务使用，可以让CanalInstance引用一个GroupEventParser，
 *   由GroupEventParser内部维护4个MysqlEventParser去4个不同的mysql实例去拉取binlog，最终合并到一起。
 *   此时业务只需要启动1个客户端，链接这个CanalInstance即可.
 *   LocalBinlogEventParser：解析本地的mysql binlog。例如将mysql的binlog文件拷贝到canal的机器上进行解析。
 * CanalEventSink接口实现类：
 *   EntryEventSink
 *   GroupEventSink：基于归并排序的sink处理
 * CanalEventStore接口实现类：
 *   目前只有MemoryEventStoreWithBuffer，基于内存buffer构建内存memory store
 * CanalMetaManager：
 *   ZooKeeperMetaManager：将元数据存存储到zk中
 *   MemoryMetaManager：将元数据存储到内存中
 *   MixedMetaManager：组合memory + zookeeper的使用模式
 *   PeriodMixedMetaManager：基于定时刷新的策略的mixed实现
 *   FileMixedMetaManager：先写内存，然后定时刷新数据到File
 *
 * @author jianghang 2012-7-12 下午12:04:58
 * @version 1.0.0
 */
public interface CanalInstance extends CanalLifeCycle {
    //这个instance对应的destination
    String getDestination();
    //数据源接入，模拟slave协议和master进行交互，协议解析，位于canal.parse模块中
    CanalEventParser getEventParser();
    //parser和store链接器，进行数据过滤，加工，分发的工作，位于canal.sink模块中
    CanalEventSink getEventSink();
    //数据存储，位于canal.store模块中
    CanalEventStore getEventStore();
    //增量订阅&消费元数据管理器，位于canal.meta模块中
    CanalMetaManager getMetaManager();
    //告警，位于canal.common块中
    CanalAlarmHandler getAlarmHandler();

    /**
     * 客户端发生订阅/取消订阅行为
     */
    boolean subscribeChange(ClientIdentity identity);

    CanalMQConfig getMqConfig();
}
